Creating Kanzi Engine plugins

Kanzi Engine plugins extend the functionality of Kanzi Engine. Kanzi Engine executes these plugins on the target platforms. Use a Kanzi Engine plugin to:

• Create custom nodes using the Kanzi Engine API, use them in your Kanzi Studio projects, and see in the Kanzi StudioPreview how they work .
• Create custom property types and messages using the Kanzi Engine API, and use them in your Kanzi Studio projects.
  When you create property types in Kanzi Engine plugins, use unique names across all plugins and Kanzi Studio projects you use in the same Kanzi application.
• Define the data entry points to your Kanzi application, and form the contract between the Kanzi application designer and developer.

To see how you can use Kanzi Engine plugins, see these examples:

• Node2D plugin example
• Node3D plugin example

Creating a Kanzi Engine plugin using the plugin template

To create a Kanzi Engine plugin using the plugin template:

1. In Kanzi Studio Quick Start screen click New Project....
   
2. In the Create New Project window set the Project Type to Kanzi Studio project with C++ plugin and application and click OK.

   Kanzi creates a Kanzi Studio project in <KanziWorkspace>/Projects/<ProjectName>/Tool_project directory and the structure for the Visual Studio solution for your project in <KanziWorkspace>/Projects/<ProjectName>/Application:

   • bin directory contains the binaries and configuration files of your project.
   • configs directory contains the configuration files for different platforms. By default Kanzi creates configuration files for several different platforms. The recommended platform for developing Kanzi applications is Microsoft Visual Studio 2010. See Deploying Kanzi applications.
   • src contains the source code for your project.
   
3. Open the Visual Studio solution for your platform in Visual Studio.
   For example, open the Visual Studio solution for the Windows platform stored in <KanziWorkspace>/Projects/<ProjectName>/Application/configs/platforms/win32.
4. The Visual Studio solution contains:
   • The project for the Kanzi Engine plugin named <ProjectName>. Here you create the Kanzi Engine plugin.
   • The project for the C++ application named <ProjectName>_executable. Here you can create the logic for your application.
5. In Visual Studio create the logic for your Kanzi application and your Kanzi Engine plugin.
6. In the Solution Explorer right-click the <ProjectName>_executable project and select Set as StartUp Project.
7. In Visual Studio select the solution configuration for your version of Visual Studio and select Build > Build Solution. If you want to build several versions at once, select the versions you want to build in Build > Batch Build.
   Visual Studio builds both the project that contains the logic of your Kanzi application and creates the dll for your Kanzi Engine plugin.
   For example, if you are still developing your application and plugin, select the GL_vs2010_Debug configuration. If you want to create a production version of your Kanzi application, select one of the available release configurations.
   
8. In Kanzi Studio in the project you created in the first step in the Library > Kanzi Engine Plugins select the <ProjectName> plugin:
   1. Right-click the plugin and select Update Kanzi Engine plugin Metadata to take into use the changes you made to the plugin in the Visual Studio plugin project.
      
   2. In the Properties enable the Is Enabled property to take the plugin into use.
      

9. Make sure that the solution configuration you used in Visual Studio to build your application and plugin projects matches the settings of your Kanzi Studio project.
   For example, if you used the GL_vs2010_Debug solution in Visual Studio, in your Kanzi Studio project in the Project > Properties set:

   • Preview OpenGL ES Wrapper to GL (Emulation through desktop OpenGL)
   • Preview Build Configuration to Debug
   • Preview Visual Studio Version to 2010

   

Creating a Kanzi Engine plugin manually

To create a Kanzi Engine plugin manually:

1. In Kanzi Studio create a new project with C++ application.
   
2. In Kanzi Studio select File > Export KZB > Export KZB Binary.
   Kanzi Studio creates the .kzb binary and configuration files from your Kanzi Studio project. Kanzi Studio stores the exported files in <KanziWorkspace>/Projects/<ProjectName>/Application/bin or the location you specify in the Binary Export Directory property in Project > Properties. The .kzb binary file contains all nodes and resources from your Kanzi Studio project, except the resources you mark in a localization table as locale packs.
   When you run your Kanzi application from Visual Studio, your Visual Studio solution reads these files to create your Kanzi application.
   
3. In Visual Studio open the Visual Studio solution for your application located in <ProjectName>/Application/configs/platforms/win32.
4. In Visual Studio select the solution configuration for your version of Visual Studio.
   For example, if you are still developing your application and plugin, select the GL_vs2010_Debug configuration. If you want to create a production version of your Kanzi application, select one of the available release configurations.
   
5. In the Solution Explorer right-click the solution and select Add > New Project. This is the project where you create the Kanzi Engine plugin.
   
   1. Select Empty Project.
   2. Name the project.
   3. Set the Location to the <ProjectName>/Application/configs/platforms/win32.
   
6. In the Solution Explorer right-click the plugin project and select Set as StartUp Project.
7. In the Solution Explorer right-click the empty project you created in the previous step, select Properties, and click Configuration Manager....
   
8. In the Configuration Manager for the project you created select <New...> configuration and set:
   
   1. Name to the same name as the name of the build configuration you selected in the third step.
      For example, set it to GL_vs2010_Debug_DLL.
   2. Deselect Create new solution configurations.
   3. Click OK.
   
9. In the Property Manager right-click the configuration you added in the previous step, select Add Existing Property Sheet..., and add:
   • <KanziWorkspace>/Engine/configs/platforms/win32/debug.props
   • <ProjectName>/Application/configs/platforms/win32/dll_application.props
   • <KanziWorkspace>/Engine/configs/platforms/win32/gl.props
   
10. In the Solution Explorer right-click the plugin project, select Properties, and set:
    • Target extension to .dll
    • Configuration type to .dll
    
11. In the Solution Explorer right-click the plugin project, select Add New Item...:
    1. Select C++ file (.cpp).
    2. Name the file.
    3. Set the Location to the <ProjectName>/Application/src.
    
12. In the Solution Explorer right-click the plugin project and select Properties:
    1. In the Property Pages window select Configuration Properties > C/C++ > Preprocessor.
    2. In the Preprocessor Definitions drop-down menu select <Edit...>.
       
    3. In the Preprocessor Definitions window add the CUSTOM_COMPONENT_API=__declspec(dllexport) definition.
       You have to add this preprocessor definition so that the .dll can exports its functionality to Kanzi Engine.
       
13. In the Solution Explorer right-click the main project and select Properties:
    1. In the Property Pages window select Configuration Properties > C/C++ > Preprocessor.
    2. In the Preprocessor Definitions drop-down menu select <Edit...>.
    3. In the Preprocessor Definitions window add the CUSTOM_COMPONENT_API=__declspec(dllimport) definition.
       You have to add this preprocessor definition to the main project so that the main project can import the functionality that the plugin .dll exports to Kanzi Engine.
    4. In the Property Pages window select Common Properties > Framework and References.
    5. Click Add New Reference... and add the reference to your plugin project.
14. In Visual Studio open the .cpp file you created in the plugin project and add the createModule, deleteModule, and getMetaclassOverride functions.
    The plugin uses these functions to get the list of functions, metaclasses, and the component inside the .dll. It the uses them to register these to Kanzi Engine.
    

    #include <kanzi/module/module.hpp>
    
    extern "C"
    {
    	CUSTOM_COMPONENT_API kanzi::Module* createModule(uint32_t kanziVersionMajor, uint32_t kanziVersionMinor);
    }
    
    class PluginModule: public kanzi::Module
    {
    	virtual MetaclassContainer getMetaclassesOverride() KZ_OVERRIDE;
    };
    
    PluginModule::MetaclassContainer PluginModule::getMetaclassesOverride()
    {
    	MetaclassContainer metaclasses;
    	return metaclasses;
    }
    
    CUSTOM_COMPONENT_API kanzi::Module* createModule(uint32_t /*kanziVersionMajor*/, uint32_t /*kanziVersionMinor*/)
    {
    	return new PluginModule;
    }

15. Select Build > Build Solution.
    The output of the build is the .dll that is the Kanzi Engine plugin you can install and use in your Kanzi Studio project. See Installing Kanzi Engine plugins.

Installing Kanzi Engine plugins

To install a Kanzi Engine plugin to a Kanzi Studio project:

1. In the Library right-click Kanzi Engine Plugins and select Import Kanzi Engine Plugin.
2. Select the .dll of the plugin you want to install and click OK.
   When you select in the Library > Kanzi Engine Plugins the plugin you imported, in the Properties you can see a list of the content that the plugin brings to the Kanzi Studio project. For example, Properties contain a list of property types, messages, and components.

3. Make sure that the solution configuration you used in Visual Studio to build your application and plugin projects matches the settings of your Kanzi Studio project.
   For example, if you used the GL_vs2010_Debug solution in Visual Studio, in your Kanzi Studio project in the Project > Properties set:

   • Preview OpenGL ES Wrapper to GL (Emulation through desktop OpenGL)
   • Preview Build Configuration to Debug
   • Preview Visual Studio Version to 2010

   

4. In the Library > Kanzi Engine Plugins select the plugin you imported and in the Properties enable the Is Enabled property.
5. Press F8, or select Project > Start Preview to start the Preview.
   You can now use the content provided by the plugin in your Kanzi Studio project.

See also

Kanzi Engine plugins

Open topic with navigation